url: docs deprecate legacy url API by jasnell · Pull Request #22715 · nodejs/node

jasnell · 2018-09-05T18:35:08Z

It's time to start the deprecation process for the legacy URL API.

Documentation-only deprecation for Node.js 11
Hopefully upgraded to Runtime-deprecation in Node.js 12

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
documentation is changed or added
commit message follows commit guidelines

nodejs-github-bot · 2018-09-05T18:35:11Z

@jasnell build started: https://ci.nodejs.org/blue/organizations/jenkins/node-test-pull-request-lite-pipeline/detail/node-test-pull-request-lite-pipeline/804/pipeline

targos

The functions should be marked as deprecated in url.md.

refack

👍 on process

jasnell · 2018-09-05T19:02:44Z

@targos ... done!

addaleax

Hopefully upgraded to Runtime-deprecation in Node.js 12

That time frame seems off by a few years?

BridgeAR · 2018-09-05T20:09:20Z

Would it be to early to add this to the pending deprecations? That would allow people who actively opt in to know that it's deprecated even without looking at the docs.

mcollina

LGTM.

TimothyGu

Unfortunately, I see #12682 as a blocker for the deprecation of the legacy URL API. We need to have a story for Express and other modules that still heavily use the legacy API (Express does so through the parseurl wrapper), whether that be a userland module or a Core API, preferably before we start the deprecation proceedings and definitely before we runtime-deprecate the API. Sorry about blocking this.

jasnell · 2018-09-05T21:42:13Z

@TimothyGu, that's precisely why this is a documentation only deprecation.

jasnell · 2018-09-05T21:43:45Z

In other words, I don't think we can actually start moving people through the migration until we start the deprecation because there won't be pressure to actually change

TimothyGu

With the commitment to address #12682 before runtime deprecation, LGTM.

TimothyGu · 2018-09-05T21:45:19Z

doc/api/deprecations.md

url.format() should be qualified to not include the overload that takes URL objects.

I'm not sure it should. I added that strictly as a convenience. The intent here is to move people away from the non-standard API and keeping that one variant un-deprecated would not make sense. Folks really should be using the href property on the URL object instead.

TimothyGu · 2018-09-05T21:46:10Z

doc/api/deprecations.md

Links for the functions and "legacy urlObject" would be nice.

Trott · 2018-09-07T20:16:06Z

doc/api/deprecations.md

+
+The [Legacy URL API][] is deprecated in favor of the newer standardized
+[WHATWG URL][] implementation. This includes uses of [`url.format()`][],
+[`url.parse()`][], [`url.resolve()`][], and the [legacy `urlObject`][].


@jasnell Is it OK with you if I change the text to this?:

The [Legacy URL API][] is deprecated. This includes [`url.format()`][], [`url.parse()`][], [`url.resolve()`][], and the [legacy `urlObject`][]. Please use the [WHATWG URL API][] instead.

(This will also require updating the link reference currently on line 1158 to say WHATWG URL API rather than WHATWG URL.)

Whatever you'd like

PR-URL: #22715 Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Gus Caplan <me@gus.host> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

jasnell · 2018-09-07T23:57:57Z

Landed in 922a1b0

PR-URL: nodejs#22765 Refs: nodejs#22715 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

Fishrock123 · 2018-12-17T23:50:55Z

I do not agree with deprecating url.format() with no suitable replacement: #25099

jasnell · 2018-12-20T15:45:02Z

Please define "suitable replacement" as that is quite subjective. The URL standard does expose ways of creating and formatting a URL that would be relatively trivial to wrap into a url.format() type of utility function is userland. Also note, the deprecation is docs-only, and was signed off by 11 collaborators (5 of whom are TSC). There were no objections prior to the deprecation landing. I see no reason to remove the deprecation for url.format()

nodejs-github-bot added deprecations Issues and PRs related to deprecations. doc Issues and PRs related to the documentations. labels Sep 5, 2018

jasnell added the semver-major PRs that contain breaking changes and should be released in the next major version. label Sep 5, 2018

jasnell requested a review from a team September 5, 2018 18:36

targos requested changes Sep 5, 2018

View reviewed changes

refack approved these changes Sep 5, 2018

View reviewed changes

targos approved these changes Sep 5, 2018

View reviewed changes

vsemozhetbyt approved these changes Sep 5, 2018

View reviewed changes

vsemozhetbyt added the url Issues and PRs related to the legacy built-in url module. label Sep 5, 2018

addaleax approved these changes Sep 5, 2018

View reviewed changes

trivikr approved these changes Sep 5, 2018

View reviewed changes

BridgeAR approved these changes Sep 5, 2018

View reviewed changes

devsnek approved these changes Sep 5, 2018

View reviewed changes

mcollina approved these changes Sep 5, 2018

View reviewed changes

TimothyGu suggested changes Sep 5, 2018

View reviewed changes

TimothyGu approved these changes Sep 5, 2018

View reviewed changes

lpinca approved these changes Sep 6, 2018

View reviewed changes

cjihrig approved these changes Sep 6, 2018

View reviewed changes

url: docs deprecate legacy url API

3a04026

jasnell force-pushed the deprecate-legacy-url branch from 66e8a36 to 3a04026 Compare September 6, 2018 14:45

Trott reviewed Sep 7, 2018

View reviewed changes

Update deprecations.md

86698e0

jasnell closed this Sep 7, 2018

tniessen mentioned this pull request Sep 8, 2018

doc: fix type of DEP0116 #22765

Closed

3 tasks

kanongil mentioned this pull request Sep 11, 2018

Use WHATWG URL for request.url hapijs/hapi#3822

Merged

Fishrock123 mentioned this pull request Dec 17, 2018

WhatWG URL provides no suitable replacement for url.format() #25099

Closed

trivikr mentioned this pull request Oct 4, 2019

Remove misleading paragraph about the Legacy URL API #29844

Closed

Uh oh!

Conversation

jasnell commented Sep 5, 2018

Checklist

Uh oh!

nodejs-github-bot commented Sep 5, 2018

Uh oh!

targos left a comment

Choose a reason for hiding this comment

Uh oh!

refack left a comment

Choose a reason for hiding this comment

Uh oh!

jasnell commented Sep 5, 2018

Uh oh!

addaleax left a comment

Choose a reason for hiding this comment

Uh oh!

BridgeAR commented Sep 5, 2018

Uh oh!

mcollina left a comment

Choose a reason for hiding this comment

Uh oh!

TimothyGu left a comment

Choose a reason for hiding this comment

Uh oh!

jasnell commented Sep 5, 2018

Uh oh!

jasnell commented Sep 5, 2018

Uh oh!

TimothyGu left a comment

Choose a reason for hiding this comment

Uh oh!

TimothyGu Sep 5, 2018

Choose a reason for hiding this comment

Uh oh!

jasnell Sep 6, 2018

Choose a reason for hiding this comment

Uh oh!

TimothyGu Sep 5, 2018

Choose a reason for hiding this comment

Uh oh!

jasnell Sep 6, 2018

Choose a reason for hiding this comment

Uh oh!

Trott Sep 7, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jasnell Sep 7, 2018

Choose a reason for hiding this comment

Uh oh!

jasnell commented Sep 7, 2018

Uh oh!

Fishrock123 commented Dec 17, 2018

Uh oh!

jasnell commented Dec 20, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

15 participants

Trott Sep 7, 2018 •

edited

Loading